iT邦幫忙

2025 iThome 鐵人賽

DAY 9
0
佛心分享-IT 人自學之術

API 實戰入門從設計到驗證系列 第 9

Day9 API 資料格式與一致性

  • 分享至 

  • xImage
  •  

在API的設計中,資料格式是溝通的語言,即使端點設計合理,如果資料格式混亂,不僅會增加開發者理解的困難,也可能造成程式錯誤或系統不穩定,因此,保持資料的一致性與標準化,是API設計的重要基礎。

  1. 常用格式
    現代API最常見的資料交換格式是JSON,結構簡單、可讀性高,也方便程式解析。相比之下XML雖然仍被部分系統使用,但JSON更輕量,也更符合網頁與行動應用的需求。

  2. 欄位命名規範
    命名方式應保持一致,例如全部使用camelCase(如userName)或snake_case(如user_name),避免在同一個API裡混用,這樣能讓開發者更快理解資料結構。

  3. 資料型別統一
    同一種資料要保持一致的型別,例如布林值固定使用truefalse,數字只用數字,不要混雜單位。若需要單位,應該額外提供欄位而不是直接寫在數字裡。

  4. 格式標準化
    日期與時間建議採用ISO 8601標準格式,例如 2025-09-15T10:00:00Z ,這樣不同系統之間不會因格式差異造成混亂,小數或金額也要統一,避免有的回傳兩位小數,有的回傳四位小數。

  5. 欄位說明清楚
    每個欄位都應該在文件中標註清楚,包括它的用途、型別、是否必填,並且提供範例,能降低使用API時的試錯成本。

  6. 回應結構一致性
    不管成功還是失敗,API回應結構應保持一致。常見做法是統一包含 statusmessage 以及 data 區塊,避免開發者需要為不同情況寫額外的解析邏輯。


上一篇
Day8 API 端點與參數設計
下一篇
Day10 API 資源與資源導向設計
系列文
API 實戰入門從設計到驗證13
圖片
  熱門推薦
圖片
{{ item.channelVendor }} | {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言